\documentclass[11pt]{book}
\usepackage{BAManual} % Bruce Rannala's custom book format
\usepackage{graphicx}
%\usepackage{mathptmx}
\usepackage{mathpazo}
\usepackage{fancyhdr}
\usepackage{amsthm}
\usepackage{natbib}
\usepackage{bbold}
\newcounter{exa}
\setcounter{exa}{0}
%_%_%_%_% upright style; roman (non-italic) text
% \newtheoremstyle begins
\newtheoremstyle{upright}
{8pt plus2pt minus4pt}
{8pt plus2pt minus4pt}
{\upshape}
{}
{\bfseries\scshape}
{}
{1em}
{}
% \newtheoremstyle ends
\theoremstyle{upright}
\newtheorem{examp}{Example}[chapter]

\begin{document}
\renewcommand{\chaptermark}[1]{
% formatting of headers and footers from http://latex.s-v-p.de/fancy/header.phtml
  \markboth{%
    \ifnum \c@secnumdepth >\m@ne
    \hfill\thechapter\quad \if @mainmatter
        \@chapapp\ \thechapter\quad
      \fi
    \fi
     #1%
  }{%
    \ifnum \c@secnumdepth >\m@ne
      \if @mainmatter
        \@chapapp\ \thechapter\quad
      \fi
    \fi
    #1%
  }%
}%
\renewcommand\sectionmark[1]{\markright{\thesection\ #1}}
\renewcommand\headrulewidth{1pt}
\renewcommand\footrulewidth{0pt}
% positioning
\fancyhead{}% delete the defaults
\fancyhead[RE,LO]{\bf\large\thepage} % right-even and left-odd
\fancyhead[LE]{\parbox{0.9\columnwidth}{\leftmark}} % even pages!
\fancyhead[RO]{\parbox{0.9\columnwidth}{\rightmark}} % odd pages!
\fancyfoot{} % clear
\pagestyle{fancy}
\renewcommand{\headrulewidth}{1pt}
\paperwidth 5in \paperheight 8in
\title{BayesAss 2.0 Manual}
\author{Bruce Rannala}
\maketitle
\newpage
\noindent
\thispagestyle{empty} \vspace{4cm} \\
\textbf{BAYESASS 2.0 MANUAL} \\
\copyright 2007 by Bruce Rannala, University of California \\
\vspace{.2cm} All rights reserved. \\
This publication may be reproduced, stored in a
retrieval system, or transmitted, in any form, or by any means,
electronic, mechanical, photocopying, recording, or otherwise, in
whole or part, but may not be modified with the permission of
the author. 
\vspace{.2cm}\\


\tableofcontents \thispagestyle{empty} \cleardoublepage
\pagenumbering{arabic}

\chapter{Getting Started: Downloading and Installation}
\chaptermark{Getting Started}

\section{Downloading BayesAss}
The BayesAss 2.0 program has not yet been officially released, but will eventually be available 
from http://rannala.org. 

\section{Compiling and Installing from Source Code}
It is possible to manually compile the program from source code for a variety of operating systems and
computer architectures. To compile the program a C++ compiler is needed; the distribution has been
extensively tested using GNU g++ (GCC) 4.1.2. A makefile is included with the source code distribution.
The program uses the GNU Scientific Library which must first be installed. The basic steps are as follows:
\begin{enumerate}
\item Download and install GSL
\item Download the latest stable source code file available at: \\
http://rannala.org/software/BA2.stable.2.*.*.tar
\item Untar the file using
\begin{verbatim}
tar -xvf BA2.stable.2.*.*.tar
\end{verbatim}
\item Edit the makefile, setting the variable PLATFORM to PLATFORM = UNIX,
PLATFORM = OSX or PLATFORM = WINDOWS
\item Compile the program by typing the command $\mathtt{make}$ in the directory
containing the source code. For example, entering the following commands in a terminal on a unix machine
will compile the program and execute it using the example batch file $\mathtt{rs.bat}$:
\begin{verbatim}
cd /home/bruce/BA2.stable.2.0.0.tar; make; ./BA2 rs.bat
\end{verbatim} 
\end{enumerate} 

\section{Installing Precompiled Binaries}
To install precompiled binaries for specific architectures and operating systems, extract the archive
file into a folder and execute the program by issuing the command $\mathtt{BA2}$ (unix and OS X) or
$\mathtt{BA2.exe}$ (Windows). To allow the program to be executed without specifying the path to
the executable file, place the binary in a directory such as /usr/local/bin and add this directory
to the PATH if needed. To check whether a directory is in the current path type
$\mathtt{echo \,\, \$PATH}$. To add the directory /home/bruce/bin to the path for example, when using 
a bash shell, add the following line to the .bashrc file:
\begin{verbatim}
PATH=$PATH:/home/bruce/bin
\end{verbatim} 

\chapter{Basic Use of BayesAss at the Command Line}
\chaptermark{BayesAss Basics}
\section{Executing BayesAss from the Command Line}
The BayesAss program is an interactive command line program. 
To execute the program, it is necessary to first open a
terminal program. In Windows, the terminal program is found in the Accessories sub-menu, while in Mac OS X
it is found in the Applications/Utilities subfolder. The Mac OS X Terminal.app program runs a bash shell
by default, as do most unix distributions. The commands that I use in my examples, although illustrated
using bash, should work with most
shells and terminal apps. To start the program type $\mathtt{BA2}$. If you receive an error message such
as
\begin{verbatim}
bash: BA2: command not found
\end{verbatim}
you will need to either add the current working directory to your PATH variable 
(by editing .bashrc for example)
or use the command $\mathtt{./BA2}$ which tells the operating system to execute the program in the current
working directory (denoted as $\mathtt{./}$). If the program executes successfully you will see a banner
displayed, followed by a command prompt
\begin{verbatim}
bruce@dirichlet:~/sandbox/bruce-code/BA2$ ./BA2
             BayesAss V.2.0 [FlatHead Lake Edition]              
               Bruce Rannala (http://rannala.org)                
         Genome Center, University of California, Davis          
            Copyright 2007, University of California             
               [enter "help;" to list commands]                
BA>
\end{verbatim}
To execute a program function enter a command (possibly followed by one or more parameters) terminated
by a semicolon. For example, to obtain a list of all available command and parameter combinations enter:
$\mathtt{BA2> help;}$ \\
which produces
\begin{verbatim}
------------------------------------------------------------
               BayesAss V.2.0: List of Commands             
------------------------------------------------------------
 bat [-I include/exclude] : Bayesian population assignment  
 bayesAss : Bayesian MCMC analysis of migrant proportions   
 citation [-C citation format] : articles to cite for BA2   
 help : print list of commands to screen                    
 printAlleles : print allele counts                         
 printData : print to screen data scanned from input file   
 pset [parameter=value] : set parameter to value            
 scan [-F file format][input file name] : open input file   
 simulate : simulate data                                   
 sset [parameter=value] : set simulation parameter to value 
 quit : terminate the program                               
------------------------------------------------------------
 Important note: all commands must be terminated with ";" 
------------------------------------------------------------
                                                            
BA>
\end{verbatim}

The available functions in BayesAss 2 are described in more detail in the remaining sections. 
The only further command we will mention here is $\mathtt{quit}$ which, as expected, 
terminates the BA2 program.

\section{Input File Format and the Scan Command}
The command for reading an input file into BayesAss is 
\begin{verbatim}
scan [-F file format][input file name]
\end{verbatim}
where the first parameter is the input file format and the second is the input file name.
Two file formats are currently accepted by BayesAss: Structure format (option -FS) and 
Immanc format (option -FI). An example input file (in Structure format) 
containing data for 10 individuals, with 5 individuals sampled from each of 2 populations, 
and each individual genotyped for 4 loci, is
given below:
\begin{verbatim}
ind0 0 0 0 A 0  
ind0 0 1 0 1 1
1.1  0 0 2 0 2 
1.1  0 0 1 1 0  
2    0 2 1 0 2 
2    0 1 0 1 2 
3    0 1 1 B 1 
3    0 2 2 0 0  
4    0 0 2 0 2  
4    0 2 1 1 0  
joe  1 0 1 0 1 
joe  1 0 2 2 0  
11   1 2 1 2 1 
11   1 1 2 0 1  
12   1 2 2 1 0  
12   1 1 2 1 0 
13   1 2 1 0 2  
13   1 1 1 2 2  
ann  1 1 1 1 0  
ann  1 0 2 2 1 
\end{verbatim}
The first column is the individual label, the second is the population label, and the remaining
columns are the alleles. Each label must be unique (either a unique individual or population)
and two rows are expected for each diploid individual. Currently, the haplotype phase is ignored.
Alphabetical characters, strings, and (positive or negative) numbers may be used for the labels.
Applying the scan command to the above file produces the following results:
\begin{verbatim}
BA>scan -FS simulate.out;
Scanning input file: simulate.out
Data File in -FS format 
Individuals: 10 Populations: 2 Loci: 4
BA>
\end{verbatim} 
The accuracy of the program in scanning the input file can be checked using the command
$\mathtt{printData}$. For the above data this produces:
\begin{verbatim}
BA>printData;

Printing Contents of Data File: simulate.out
------------------------------------------------------------
 Indiv.    Popln.                   Genotypes
------------------------------------------------------------
 ind0      0         0/1       0/0       A/1       0/1       
 1.1       0         0/0       2/1       0/1       2/0       
 2         0         2/1       1/0       0/1       2/2       
 3         0         1/2       1/2       B/0       1/0       
 4         0         0/2       2/1       0/1       2/0       
 joe       1         0/0       1/2       0/2       1/0       
 11        1         2/1       1/2       2/0       1/1       
 12        1         2/1       2/2       1/1       0/0       
 13        1         2/1       1/1       0/2       2/2       
 ann       1         1/0       1/2       1/2       0/1       
------------------------------------------------------------

BA>
\end{verbatim}
Another function for examining the data is $\mathtt{printAlleles}$
which prints to screen a summary of the allele counts in each population:
\begin{verbatim}
BA>printAlleles;

Population: 0
Locus 0: 0:4 1:3 2:3 
Locus 1: 0:3 2:3 1:4 
Locus 2: A:1 1:4 0:4 B:1 2:0 
Locus 3: 0:4 1:2 2:4 

Population: 1
Locus 0: 0:3 1:4 2:3 
Locus 1: 0:0 2:5 1:5 
Locus 2: A:0 1:3 0:3 B:0 2:4 
Locus 3: 0:4 1:4 2:2 

BA>
\end{verbatim}
A new input file may be scanned at any time during a BayesAss session using the scan command. 
Scanning a new input file into memory deletes from memory the data of any previously scanned 
input file. The current data will always be the most recently scanned input file.
An example input file (in Immanc format) containing data for 15 individuals from two populations, genotyped
for two loci, is given below:
\begin{verbatim}
ind1	pop1	locA	194	198
ind2	pop1	locA	198	198
ind3	pop1	locA	192	198
ind4	pop1	locA	190	198
ind5	pop1	locA	190	194
ind6	pop1	locA	194	198
ind7	pop1	locA	190	198
ind8	pop1	locA	184	190
ind9	pop1	locA	190	192
ind10	pop1	locA	184	192
ind11	pop2	locA	184	194
ind12	pop2	locA	190	194
ind13	pop2	locA	184	194
ind14	pop2	locA	192	194
ind15	pop2	locA	184	194
ind1	pop1	locB	158	162
ind2	pop1	locB	148	162
ind3	pop1	locB	150	158
ind4	pop1	locB	152	158
ind5	pop1	locB	162	162
ind6	pop1	locB	152	158
ind7	pop1	locB	152	156
ind8	pop1	locB	158	162
ind9	pop1	locB	162	162
ind10	pop1	locB	162	162
ind11	pop2	locB	162	162
ind12	pop2	locB	150	162
ind13	pop2	locB	158	162
ind14	pop2	locB	152	156
ind15	pop2	locB	156	158
\end{verbatim}
The first column is the individual label, the second is the population label, the third is the
locus label and the remaining 2 columns are the alleles at each locus that make up a genotype.
In this case, each individual has a row entry for every locus; the order of the alleles determines
the haplotype phase (this information is not currently used and so the ordering is arbitrary).
Applying the scan command to the file containing the above data produces the following result:
\begin{verbatim}
BA>scan -FI data/BP3.inp;
Scanning input file: data/BP3.inp
Data File in -FI format 
Individuals: 15 Populations: 2 Loci: 2
BA>
\end{verbatim}
and the printData command produces
\begin{verbatim}
BA>printData;

Printing Contents of Data File: data/BP3.inp
------------------------------------------------------------
 Indiv.    Popln.                   Genotypes
------------------------------------------------------------
 ind1      pop1         194/198   158/162   
 ind2      pop1         198/198   148/162   
 ind3      pop1         192/198   150/158   
 ind4      pop1         190/198   152/158   
 ind5      pop1         190/194   162/162   
 ind6      pop1         194/198   152/158   
 ind7      pop1         190/198   152/156   
 ind8      pop1         184/190   158/162   
 ind9      pop1         190/192   162/162   
 ind10     pop1         184/192   162/162   
 ind11     pop2         184/194   162/162   
 ind12     pop2         190/194   150/162   
 ind13     pop2         184/194   158/162   
 ind14     pop2         192/194   152/156   
 ind15     pop2         184/194   156/158   
------------------------------------------------------------

BA>
\end{verbatim}  
It is recommended that the printData command always be used to check that a data file has
been correctly scanned into memory.

\section{Bayesian Assignment Tests for Individuals}
One of the simplest analyses available in BayesAss is to calculate the posterior population 
assignment probability for individual $j$ to
population $i$ using the formula
\begin{displaymath}
\mathrm{Pr}(j \rightarrow i|\mathbf{X}_j,\mathbf{X})=
\frac{\mathrm{Pr}(\mathbf{X}_j|i,\mathbf{X})g(i)}{\sum_{l=1}^k \mathrm{Pr}(\mathbf{X}_j|l,\mathbf{X})g(l)},
\end{displaymath}
To carry out individual posterior probability population assignments for a set of individuals we use
the Bayesian Assignment Test function in BayesAss. $\mathtt{bat}$. The following analysis generates 
assignment probabilities for individuals $\mathtt{joe}$ and $\mathtt{ind0}$:
\begin{verbatim}
BA>scan -FS simulate.out;
Scanning input file: simulate.out
Data File in -FS format 
Individuals: 10 Populations: 2 Loci: 4
BA>pset alist=(joe,ind0);
                                                            
------------------------------------------------------------
               BayesAss V.2.0: Parameter Settings           
------------------------------------------------------------
 alist=(joe,ind0)
 MCMCreps=50000
 MCMCthin=1000
 MCMCdisplay=1000
 MCMCburnin=5000
 MCMCwindow=0.1
 outfile=BA2.out
 Dirichlet=100
 RandomSeed=1
------------------------------------------------------------
                                                            
BA>bat;
------------------------------------------------------------
Bayesian Population Assignment
------------------------------------------------------------
    Population:  0         1         
Individual:
joe              0.0797    0.92      
ind0             0.978     0.0225    
------------------------------------------------------------

BA>
\end{verbatim}
where the command
\begin{verbatim}
pset alist=(joe,ind0);
\end{verbatim}
defines a list of individuals (joe and ind0) to be assigned. By default, the
individuals themselves are excluded when calculating assignment probabilities.
For small samples, including the individual to be assigned may bias the assignment
probability in favor of assignment to the current (sampled) population. 
The option -I overrides the default and forces bat to include the assigned individual 
in calculating assignment probabilities: 
\begin{verbatim}
BA>bat -I;     
------------------------------------------------------------
Bayesian Population Assignment
------------------------------------------------------------
--Assigned individual included to calculate probability--
    Population:  0         1         
Individual:
joe              0.0266    0.973     
ind0             0.993     0.0072    
------------------------------------------------------------

BA>
\end{verbatim} 
The Bayesian assignment test implemented in BayeAss is described (for haploid recombining loci) in
\cite[][]{}. The test assumes that a set of populations are genetically isolated and the unknown
individual to be assigned is a member of one of the populations. This is appropriate for assigning
pathogenic organisms isolated from an infected individual to a population source, for example. 

\chapter{Inferring Migrant Proportions and Migrant Ancestries}
\chaptermark{Inferring Migration}



\chapter{Simulating Population Samples}
\chaptermark{Simulation}

 
\appendix
 
\chapter{Example Analyses}
\chaptermark{Examples}

 
\bibliographystyle{ajhg}
\bibliography{/home/bruce/working/Reprints-Biblios/reprints/topics/reprints}
\end{document}
